<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>procman: Quick Start Tutorial</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">procman
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Python&#160;API</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Quick Start Tutorial </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This section provides a brief introduction to Procman and controlling processes with a deputy and a sheriff.</p>
<p>There are two types of programs in Procman - the deputy (<code>bot-procman-deputy</code>) and the sheriff (<code>bot-procman-sheriff</code>).</p>
<ul>
<li>Deputies control processes, and there must be at least one deputy.</li>
<li>Sheriffs control deputies, and there can be at most one sheriff.</li>
</ul>
<p>To get started, we'll show you how to run the deputy and the sheriff, and create and manage commands.</p>
<ul>
<li><a class="el" href="procman_tutorial.html#procman_tutorial_starting">Starting a deputy and a sheriff</a></li>
<li><a class="el" href="procman_tutorial.html#procman_tutorial_command_creation">Creating a command</a></li>
<li><a class="el" href="procman_tutorial.html#procman_tutorial_command_managing">Managing commands</a></li>
<li><a class="el" href="procman_tutorial.html#procman_tutorial_config">Saving and loading configurations</a></li>
</ul>
<h1><a class="anchor" id="procman_tutorial_starting"></a>
Starting a deputy and a sheriff</h1>
<p>First, open up your favorite terminal program and run the deputy command:</p>
<div class="fragment"><div class="line">bot-procman-deputy</div>
</div><!-- fragment --><p>Then, in another terminal, launch the sheriff GUI.</p>
<div class="fragment"><div class="line">bot-procman-sheriff</div>
</div><!-- fragment --><p>When you run the sheriff, you should see a GUI that looks something like this:</p>
<div class="image">
<img src="sheriff-gui-empty.png" alt="sheriff-gui-empty.png"/>
<div class="caption">
bot-procman-sheriff with one deputy and no commands.</div></div>
<p> There are three panes in the sheriff GUI:</p>
<ul>
<li>Top left: the command pane</li>
<li>Top right: the deputy pane</li>
<li>Bottom: the console pane</li>
</ul>
<p>The <em>command pane</em> shows all the commands managed by Procman. Since we haven't created any commands, there isn't anything to see there yet.</p>
<p>The <em>deputy pane</em> shows all the deputies detected by the sheriff. We've started one deputy, so it shows up in the top right. Deputies are always named, and the default name is the computer hostname where the deputy process is running. In this case, the hostname is "contact", so the deputy is named "contact" as well.</p>
<p>The <em>console pane</em> shows console output (stdout and stderr) from running commands, and also status information from the sheriff.</p>
<h1><a class="anchor" id="procman_tutorial_command_creation"></a>
Creating a command</h1>
<p>To create a command, select the menu item "Commands -&gt; New command".</p>
<div class="image">
<img src="sheriff-gui-add-command-menu.png" alt="sheriff-gui-add-command-menu.png"/>
<div class="caption">
Adding a command using the menu bar.</div></div>
<p> Following that, a dialog box should appear with several options to fill out.</p>
<div class="image">
<img src="sheriff-gui-add-command.png" alt="sheriff-gui-add-command.png"/>
<div class="caption">
Add command dialog.</div></div>
<p> The options are:</p>
<ul>
<li><code>Deputy</code> - which deputy should manage the command.</li>
<li><code>Command</code> - the command to execute and any command-line arguments.</li>
<li><code>Name</code> - a name for the command, used for display purposes and to identify the command.</li>
<li><code>Group</code> - commands can be grouped together, or not.</li>
<li><code>Auto-restart</code> - if checked, deputies will automatically restart commands when they terminate.</li>
</ul>
<p>In the image above, we've set the command to <code>xterm</code>, a fairly common terminal emulator. If you don't have <code>xterm</code> installed, replace the command with something you do have on your system. We've also named the command "terminal
emulator".</p>
<h1><a class="anchor" id="procman_tutorial_command_managing"></a>
Managing commands</h1>
<p>Now that we have a command, we can run it. Click on the command in the command pane so that it is highlighted. Once the command is selected, click on the menu bar item "Commands -&gt; Start".</p>
<div class="image">
<img src="sheriff-gui-start-command-menu.png" alt="sheriff-gui-start-command-menu.png"/>
</div>
<p>You should now see the <code>xterm</code> terminal emulator popup, and the status of the command should change to "Running".</p>
<div class="image">
<img src="sheriff-gui-command-running.png" alt="sheriff-gui-command-running.png"/>
</div>
<p>And that's basically it.</p>
<p>You can stop, restart, move, and edit the selected command using the "Commands" menu.</p>
<p>There are a bunch more features to Procman, but creating, starting, and stopping processes is its core functionality.</p>
<h1><a class="anchor" id="procman_tutorial_config"></a>
Saving and loading configurations</h1>
<p>It's often useful to save the commands you've created so that you can easily load them and run them again later on. To do this, select "File -&gt; Save config
as", and then select a filename.</p>
<p>The configuration files are human-readable, so if you save the configuration above and opened up the file in a text editor, you'd see something like the following:</p>
<pre class="fragment">cmd "terminal emulator" {
    exec = "xterm";
    host = "contact";
}
</pre><p>It should be pretty straightforward to figure out the format, and you can edit the configuration files directly with a text editor. For more information on the configuration file format, see the <a class="el" href="procman_config_file.html">documentation on configuration files</a>.</p>
<p>To load a configuration, click on the menu bar item "File -&gt; load config". </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sat Oct 12 2013 01:18:29 for procman by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.3.1
</small></address>
</body>
</html>
